home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Environments / PowerLisp 2.01 / Supplemental Documentation / Documentation / Chapter 10. Symbols < prev    next >
Text File  |  1995-03-27  |  21KB  |  481 lines
  1. Common Lisp the Language, 2nd Edition
  2. -------------------------------------------------------------------------------
  3.  
  4. 10. Symbols
  5.  
  6. A Lisp symbol is a data object that has three user-visible components:
  7.  
  8.    *  The property list is a list that effectively provides each symbol with
  9.      many modifiable named components.
  10.  
  11.    *  The print name must be a string, which is the sequence of characters used
  12.      to identify the symbol. Symbols are of great use because a symbol can be
  13.      located once its name is given (typed, say, on a keyboard). One may
  14.      ordinarily not alter a symbol's print name.
  15.  
  16. [change_begin]
  17. X3J13 voted in March 1989 (CHARACTER-PROPOSAL)   to specify it is an error to
  18. alter a print name.
  19. [change_end]
  20.  
  21.    *  The package cell must refer to a package object. A package is a data
  22.      structure used to locate a symbol once given the symbol's name. A symbol
  23.      is uniquely identified by its name only when considered relative to a
  24.      package. A symbol may appear in many packages, but it can be owned by at
  25.      most one package. The package cell points to the owner, if any. Package
  26.      cells are discussed along with packages in chapter 11.
  27.  
  28. A symbol may actually have other components for use by the implementation. One
  29. of the more important uses of symbols is as names for program variables; it is
  30. frequently desirable for the implementor to use certain components of a symbol
  31. to implement the semantics of variables. See symbol-value and symbol-function.
  32. However, there are several possible implementation strategies, and so such
  33. possible components are not described here.
  34.  
  35. -------------------------------------------------------------------------------
  36.  
  37.    *  The Property List
  38.    *  The Print Name
  39.    *  Creating Symbols
  40.  
  41. -------------------------------------------------------------------------------
  42.  
  43. 10.1. The Property List
  44.  
  45. Since its inception, Lisp has associated with each symbol a kind of tabular
  46. data structure called a property list (plist for short). A property list
  47. contains zero or more entries; each entry associates with a key (called the
  48. indicator), which is typically a symbol, an arbitrary Lisp object (called the
  49. value or, sometimes, the property). There are no duplications among the
  50. indicators; a property list may only have one property at a time with a given
  51. name. In this way, given a symbol and an indicator (another symbol), an
  52. associated value can be retrieved.
  53.  
  54. A property list is very similar in purpose to an association list. The
  55. difference is that a property list is an object with a unique identity; the
  56. operations for adding and removing property-list entries are destructive
  57. operations that alter the property list rather than making a new one.
  58. Association lists, on the other hand, are normally augmented non-destructively
  59. (without side effects) by adding new entries to the front (see acons and
  60. pairlis).
  61.  
  62. A property list is implemented as a memory cell containing a list with an even
  63. number (possibly zero) of elements. (Usually this memory cell is the
  64. property-list cell of a symbol, but any memory cell acceptable to setf can be
  65. used if getf and remf are used.) Each pair of elements in the list constitutes
  66. an entry; the first item is the indicator, and the second is the value. Because
  67. property-list functions are given the symbol and not the list itself,
  68. modifications to the property list can be recorded by storing back into the
  69. property-list cell of the symbol.
  70.  
  71. When a symbol is created, its property list is initially empty. Properties are
  72. created by using get within a setf form.
  73.  
  74. Common Lisp does not use a symbol's property list as extensively as earlier
  75. Lisp implementations did. Less-used data, such as compiler, debugging, and
  76. documentation information, is kept on property lists in Common Lisp.
  77.  
  78. -------------------------------------------------------------------------------
  79. Compatibility note: In older Lisp implementations, the print name, value, and
  80. function definition of a symbol were kept on its property list. The value cell
  81. was introduced into MacLisp and Interlisp to speed up access to variables;
  82. similarly for the print-name cell and function cell (MacLisp does not use a
  83. function cell). Recent Lisp implementations such as Spice Lisp, Lisp Machine
  84. Lisp, and NIL have introduced all of these cells plus the package cell. None of
  85. the MacLisp system property names (expr, fexpr, macro, array, subr, lsubr,
  86. fsubr, and in former times value and pname) exist in Common Lisp.
  87.  
  88. In Common Lisp, the notion of ``disembodied property list'' introduced in
  89. MacLisp is eliminated. It tended to be used for rather kludgy things, and in
  90. Lisp Machine Lisp is often associated with the use of locatives (to make it
  91. ``off by one'' for searching alternating keyword lists). In Common Lisp special
  92. setf-like property-list functions are introduced: getf and remf.
  93. -------------------------------------------------------------------------------
  94.  
  95. [Function]
  96. get symbol indicator &optional default
  97.  
  98. get searches the property list of symbol for an indicator eq to indicator. The
  99. first argument must be a symbol. If one is found, then the corresponding value
  100. is returned; otherwise default is returned.
  101.  
  102. If default is not specified, then nil is used for default.
  103.  
  104. Note that there is no way to distinguish an absent property from one whose
  105. value is default.
  106.  
  107. (get x y) == (getf (symbol-plist x) y)
  108.  
  109. Suppose that the property list of foo is (bar t baz 3 hunoz "Huh?"). Then, for
  110. example:
  111.  
  112. (get 'foo 'baz) => 3
  113. (get 'foo 'hunoz) => "Huh?"
  114. (get 'foo 'zoo) => nil
  115.  
  116. -------------------------------------------------------------------------------
  117. Compatibility note: In MacLisp, the first argument to get could be a list, in
  118. which case the cdr of the list was treated as a so-called ``disembodied
  119. property list.'' The first argument to get could also be any other object, in
  120. which case get would always return nil. In Common Lisp, it is an error to give
  121. anything but a symbol as the first argument to get.
  122.  
  123. What Common Lisp calls get, Interlisp calls getprop.
  124.  
  125. What MacLisp and Interlisp call putprop is accomplished in Common Lisp by using
  126. get with setf.
  127. -------------------------------------------------------------------------------
  128.  
  129. setf may be used with get to create a new property-value pair, possibly
  130. replacing an old pair with the same property name. For example:
  131.  
  132. (get 'clyde 'species) => nil
  133. (setf (get 'clyde 'species) 'elephant) => elephant
  134. and now (get 'clyde 'species) => elephant
  135.  
  136. The default argument may be specified to get in this context; it is ignored by
  137. setf but may be useful in such macros as push that are related to setf:
  138.  
  139. (push item (get sym 'token-stack '(initial-item)))
  140.  
  141. means approximately the same as
  142.  
  143. (setf (get sym 'token-stack '(initial-item))
  144.       (cons item (get sym 'token-stack '(initial-item))))
  145.  
  146. which in turn would be treated as simply
  147.  
  148. (setf (get sym 'token-stack)
  149.       (cons item (get sym 'token-stack '(initial-item))))
  150.  
  151. [change_begin]
  152. X3J13 voted in March 1989 (REMF-DESTRUCTION-UNSPECIFIED)   to clarify the
  153. permissible side effects of certain operations; (setf (get symbol indicator)
  154. newvalue) is required to behave exactly the same as (setf (getf (symbol-plist
  155. symbol) indicator) newvalue).
  156. [change_end]
  157.  
  158. [Function]
  159. remprop symbol indicator
  160.  
  161. This removes from symbol the property with an indicator eq to indicator. The
  162. property indicator and the corresponding value are removed by destructively
  163. splicing the property list. It returns nil if no such property was found, or
  164. non-nil if a property was found.
  165.  
  166. (remprop x y) == (remf (symbol-plist x) y)
  167.  
  168. For example, if the property list of foo is initially
  169.  
  170. (color blue height 6.3 near-to bar)
  171.  
  172. then the call
  173.  
  174. (remprop 'foo 'height)
  175.  
  176. returns a non-nil value after altering foo's property list to be
  177.  
  178. (color blue near-to bar)
  179.  
  180. [change_begin]
  181. X3J13 voted in March 1989 (REMF-DESTRUCTION-UNSPECIFIED)   to clarify the
  182. permissible side effects of certain operations; (remprop symbol indicator) is
  183. required to behave exactly the same as (remf (symbol-plist symbol) indicator).
  184. [change_end]
  185.  
  186. [Function]
  187. symbol-plist symbol
  188.  
  189. This returns the list that contains the property pairs of symbol; the contents
  190. of the property-list cell are extracted and returned.
  191.  
  192. Note that using get on the result of symbol-plist does not work. One must give
  193. the symbol itself to get or else use the function getf.
  194.  
  195. setf may be used with symbol-plist to destructively replace the entire property
  196. list of a symbol. This is a relatively dangerous operation, as it may destroy
  197. important information that the implementation may happen to store in property
  198. lists. Also, care must be taken that the new property list is in fact a list of
  199. even length.
  200.  
  201. -------------------------------------------------------------------------------
  202. Compatibility note: In MacLisp, this function is called plist; in Interlisp, it
  203. is called getproplist.
  204. -------------------------------------------------------------------------------
  205.  
  206. [Function]
  207. getf place indicator &optional default
  208.  
  209. getf searches the property list stored in place for an indicator eq to
  210. indicator. If one is found, then the corresponding value is returned; otherwise
  211. default is returned. If default is not specified, then nil is used for default.
  212. Note that there is no way to distinguish an absent property from one whose
  213. value is default. Often place is computed from a generalized variable
  214. acceptable to setf.
  215.  
  216. setf may be used with getf, in which case the place must indeed be acceptable
  217. as a place to setf. The effect is to add a new property-value pair, or update
  218. an existing pair, in the property list kept in the place. The default argument
  219. may be specified to getf in this context; it is ignored by setf but may be
  220. useful in such macros as push that are related to setf. See the description of
  221. get for an example of this.
  222.  
  223. [change_begin]
  224. X3J13 voted in March 1989 (REMF-DESTRUCTION-UNSPECIFIED)   to clarify the
  225. permissible side effects of certain operations; setf used with getf is
  226. permitted to perform a setf on the place or on any part, car or cdr, of the
  227. top-level list structure held by that place.
  228.  
  229. X3J13 voted in March 1988 (PUSH-EVALUATION-ORDER)   to clarify order of
  230. evaluation (see section 7.2).
  231. [change_end]
  232.  
  233. -------------------------------------------------------------------------------
  234. Compatibility note: The Interlisp function listget is similar to getf. The
  235. Interlisp function listput is similar to using getf with setf.
  236. -------------------------------------------------------------------------------
  237.  
  238. [Macro]
  239. remf place indicator
  240.  
  241. This removes from the property list stored in place the property with an
  242. indicator eq to indicator. The property indicator and the corresponding value
  243. are removed by destructively splicing the property list. remf returns nil if no
  244. such property was found, or some non-nil value if a property was found. The
  245. form place may be any generalized variable acceptable to setf. See remprop.
  246.  
  247. [change_begin]
  248. X3J13 voted in March 1989 (REMF-DESTRUCTION-UNSPECIFIED)   to clarify the
  249. permissible side effects of certain operations; remf is permitted to perform a
  250. setf on the place or on any part, car or cdr, of the top-level list structure
  251. held by that place.
  252.  
  253. X3J13 voted in March 1988 (PUSH-EVALUATION-ORDER)   to clarify order of
  254. evaluation (see section 7.2).
  255. [change_end]
  256.  
  257. [Function]
  258. get-properties place indicator-list
  259.  
  260. get-properties is like getf, except that the second argument is a list of
  261. indicators. get-properties searches the property list stored in place for any
  262. of the indicators in indicator-list until it finds the first property in the
  263. property list whose indicator is one of the elements of indicator-list.
  264. Normally place is computed from a generalized variable acceptable to setf.
  265.  
  266. get-properties returns three values. If any property was found, then the first
  267. two values are the indicator and value for the first property whose indicator
  268. was in indicator-list, and the third is that tail of the property list whose
  269. car was the indicator (and whose cadr is therefore the value). If no property
  270. was found, all three values are nil. Thus the third value serves as a flag
  271. indicating success or failure and also allows the search to be restarted, if
  272. desired, after the property was found.
  273.  
  274. -------------------------------------------------------------------------------
  275.  
  276. 10.2. The Print Name
  277.  
  278. Every symbol has an associated string called the print name. This string is
  279. used as the external representation of the symbol: if the characters in the
  280. string are typed in to read (with suitable escape conventions for certain
  281. characters), it is interpreted as a reference to that symbol (if it is
  282. interned); and if the symbol is printed, print types out the print name. For
  283. more information, see the sections on the reader (section 22.1.1) and printer
  284. (section 22.1.6).
  285.  
  286. [Function]
  287. symbol-name sym
  288.  
  289. This returns the print name of the symbol sym. For example:
  290.  
  291. (symbol-name 'xyz) => "XYZ"
  292.  
  293. It is an extremely bad idea to modify a string being used as the print name of
  294. a symbol. Such a modification may tremendously confuse the function read and
  295. the package system.
  296.  
  297. [change_begin]
  298. X3J13 voted in March 1989 (CHARACTER-PROPOSAL)   to specify that it is an error
  299. to modify a string being used as the print name of a symbol.
  300. [change_end]
  301.  
  302. -------------------------------------------------------------------------------
  303.  
  304. 10.3. Creating Symbols
  305.  
  306. Symbols can be used in two rather different ways. An interned symbol is one
  307. that is indexed by its print name in a catalogue called a package. A request to
  308. locate a symbol with that print name results in the same (eq) symbol. Every
  309. time input is read with the function read, and that print name appears, it is
  310. read as the same symbol. This property of symbols makes them appropriate to use
  311. as names for things and as hooks on which to hang permanent data objects (using
  312. the property list, for example).
  313.  
  314. Interned symbols are normally created automatically; the first time something
  315. (such as the function read) asks the package system for a symbol with a given
  316. print name, that symbol is automatically created. The function used to ask for
  317. an interned symbol is intern, or one of the functions related to intern.
  318.  
  319. Although interned symbols are the most commonly used, they will not be
  320. discussed further here. For more information, see chapter 11.
  321.  
  322. An uninterned symbol is a symbol used simply as a data object, with no special
  323. cataloguing (it belongs to no particular package). An uninterned symbol is
  324. printed as #: followed by its print name. The following are some functions for
  325. creating uninterned symbols.
  326.  
  327. [Function]
  328. make-symbol print-name
  329.  
  330. (make-symbol print-name) creates a new uninterned symbol, whose print name is
  331. the string print-name. The value and function bindings will be unbound and the
  332. property list will be empty.
  333.  
  334. The string actually installed in the symbol's print-name component may be the
  335. given string print-name or may be a copy of it, at the implementation's
  336. discretion. The user should not assume that (symbol-name (make-symbol x)) is eq
  337. to x, but also should not alter a string once it has been given as an argument
  338. to make-symbol.
  339.  
  340. -------------------------------------------------------------------------------
  341. Compatibility note: An implementation might choose, for example, to copy the
  342. string to some read-only area, in the expectation that it will never be
  343. altered.
  344. -------------------------------------------------------------------------------
  345.  
  346. [Function]
  347. copy-symbol sym &optional copy-props
  348.  
  349. This returns a new uninterned symbol with the same print name as sym.
  350.  
  351. [change_begin]
  352. X3J13 voted in March 1989 (COPY-SYMBOL-PRINT-NAME)   that the print name of the
  353. new symbol is required to be the same only in the sense of string=; in other
  354. words, an implementation is permitted (but not required) to make a copy of the
  355. print name. User programs should not assume that the print names of the old and
  356. new symbols will be eq, although they may happen to be eq in some
  357. implementations.
  358. [change_end]
  359.  
  360. If copy-props is non-nil, then the initial value and function definition of the
  361. new symbol will be the same as those of sym, and the property list of the new
  362. symbol will be a copy of sym's.
  363.  
  364. [change_begin]
  365. X3J13 voted in March 1989 (COPY-SYMBOL-COPY-PLIST)   to clarify that only the
  366. top-level conses of the property list are copied; it is as if (copy-list
  367. (symbol-plist sym)) were used as the property list of the new symbol.
  368. [change_end]
  369.  
  370. If copy-props is nil (the default), then the new symbol will be unbound and
  371. undefined, and its property list will be empty.
  372.  
  373. [Function]
  374. gensym &optional x
  375.  
  376. gensym invents a print name and creates a new symbol with that print name. It
  377. returns the new, uninterned symbol.
  378.  
  379. The invented print name consists of a prefix (which defaults to G), followed by
  380. the decimal representation of a number.
  381.  
  382. [old_change_begin]
  383. The number is increased by 1 every time gensym is called.
  384.  
  385. If the argument x is present and is an integer, then x must be non-negative,
  386. and the internal counter is set to x for future use; otherwise the internal
  387. counter is incremented. If x is a string, then that string is made the default
  388. prefix for this and future calls to gensym. After handling the argument, gensym
  389. creates a symbol as it would with no argument. For example:
  390.  
  391. (gensym) => G7
  392. (gensym "FOO-") => FOO-8
  393. (gensym 32) => FOO-32
  394. (gensym) => FOO-33
  395. (gensym "GARBAGE-") => GARBAGE-34
  396.  
  397. [old_change_end]
  398.  
  399. gensym is usually used to create a symbol that should not normally be seen by
  400. the user and whose print name is unimportant except to allow easy distinction
  401. by eye between two such symbols. The optional argument is rarely supplied. The
  402. name comes from ``generate symbol,'' and the symbols produced by it are often
  403. called ``gensyms.''
  404.  
  405. -------------------------------------------------------------------------------
  406. Compatibility note: In earlier versions of Lisp, such as MacLisp and Interlisp,
  407. the print name of a gensym was of fixed length, consisting of a single letter
  408. and a fixed-length decimal representation with leading zeros if necessary, for
  409. example, G0007. This convention was motivated by an implementation
  410. consideration, namely that the name should fit into a single machine word,
  411. allowing a quick and clever implementation. Such considerations are less
  412. relevant in Common Lisp. The consistent use of mnemonic prefixes can make it
  413. easier for the programmer, when debugging, to determine what code generated a
  414. particular symbol. The elimination of the fixed-length decimal representation
  415. prevents the same name from being used twice unless the counter is explicitly
  416. reset.
  417. -------------------------------------------------------------------------------
  418.  
  419. If it is desirable for the generated symbols to be interned, and yet guaranteed
  420. to be symbols distinct from all others, then the function gentemp may be more
  421. appropriate to use.
  422.  
  423. [change_begin]
  424. X3J13 voted in March 1989 (GENSYM-NAME-STICKINESS)   to alter the specification
  425. of gensym so that supplying an optional argument (whether a string or a number)
  426. does not alter the internal state maintained by gensym. Instead, the internal
  427. counter is made explicitly available as a variable named *gensym-counter*.
  428.  
  429. If a string argument is given to gensym, that string is used as the prefix;
  430. otherwise ``G'' is used. If a number is provided, its decimal representation is
  431. used, but the internal counter is unaffected. X3J13 deprecates the use of a
  432. number as an argument.
  433.  
  434. [Variable]
  435. *gensym-counter*
  436.  
  437. X3J13 voted in March 1989 (GENSYM-NAME-STICKINESS)   to add *gensym-counter*,
  438. which holds the state of the gensym counter; that is, gensym uses the decimal
  439. representation of its value as part of the generated name and then increments
  440. its value.
  441.  
  442. The initial value of this variable is implementation-dependent but will be a
  443. non-negative integer.
  444.  
  445. The user may assign to or bind this variable at any time, but its value must
  446. always be a non-negative integer.
  447. [change_end]
  448.  
  449. [Function]
  450. gentemp &optional prefix package
  451.  
  452. gentemp, like gensym, creates and returns a new symbol. gentemp differs from
  453. gensym in that it interns the symbol (see intern) in the package (which
  454. defaults to the current package; see *package*). gentemp guarantees the symbol
  455. will be a new one not already existing in the package. It does this by using a
  456. counter as gensym does, but if the generated symbol is not really new, then the
  457. process is repeated until a new one is created. There is no provision for
  458. resetting the gentemp counter. Also, the prefix for gentemp is not remembered
  459. from one call to the next; if prefix is omitted, the default prefix T is used.
  460.  
  461. [Function]
  462. symbol-package sym
  463.  
  464. Given a symbol sym, symbol-package returns the contents of the package cell of
  465. that symbol. This will be a package object or nil.
  466.  
  467. [Function]
  468. keywordp object
  469.  
  470. The argument may be any Lisp object. The predicate keywordp is true if the
  471. argument is a symbol and that symbol is a keyword (that is, belongs to the
  472. keyword package). Keywords are those symbols that are written with a leading
  473. colon. Every keyword is a constant, in the sense that it always evaluates to
  474. itself. See constantp.
  475.  
  476. -------------------------------------------------------------------------------
  477.  
  478.  
  479.  
  480.  
  481.